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1.0 RELATED DOCUMENTATION 


This manual supplements the manual BAS/C on RSX-11M/M-PLUS Systems. 
Both manuals are included in the documentation set shipped to Tool Kit users 
who have ordered BASIC-PLUS-2. Also included in that set are the BASIC Ref- 
erence Manual and the BASIC User’s Guide, and the BAS/C Pocket Reference 
Guide. See these three documents for additional information on BASIC and 
BASIC-PLUS-2 on RSX systems. The Pocket Reference Guide is useful for 
quick reference. 


For information on the current release of Professional Tool Kit BASIC-PLUS-2, 
its installation and known problems, see the Professional Too! Kit BASIC- 
PLUS-2 Installation Guide and Release Notes. 


2.0 PROFESSIONAL TOOL KIT BASIC-PLUS-2 


BASIC-PLUS-2 is a programming language that uses familiar words and math- 
ematical notations. With Tool Kit BASIC-PLUS-2 you can create applications on 
an RSX-11M/M-PLUS or VAX/VMS host system that run on the Professional 
Operating System (P/OS). This manual describes the differences between 
BASIC-PLUS-2 on RSX systems and Tool Kit BASIC-PLUS-2. 


The material here is intended for programmers experienced with BASIC- 
PLUS-2 on RSX systems. 
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3.0 DEVELOPMENT CYCLE 


The development cycle for Tool Kit BASIC-PLUS-2 applications (Figure 1) con- 
sists of the following steps: 


1. Write source program. 
2. Compile source program, creating object module file. 
L] Compile with /DEBUG to debug at run time. 
[] Compile without /DEBUG when program is error-free. 


3. Build command file and overlay descriptor language file. You may need 
to edit these files (See Sections 3.5 and 3.6) 


4. Task build to create executable task image file. 


Write application installation file; move it and the task to the Profes- 
sional. 


6. Runtask on the Professional. If desired, debug using REDIRECT com- 
mand and terminal attached to the Professional workstation. 


7. Run Application Diskette Builder when program is error-free, creating 
final diskette. 


The following sections present specific details of application development in 
Tool Kit BASIC-PLUS-2. For a complete description of each stage in Tool Kit 
application development, you should refer to the Too/ Kit User’s Guide. Also 
note that, with the Tool Kit, you can create application diskettes that will run on 
P/OS Diskette and/or P/OS Hard Disk. There are some important differences in 
the application development cycle for these two environments. Refer to the Too/ 
Kit User’s Guide for full details. This document focuses on application develop- 
ment for the P/OS Hard Disk Environment. 


3.1 Writing the Source Program 


The BASIC-PLUS-2 source program can include external subroutine calls to 
access P/OS facilities from your program. The external subroutine calls are 
described in the Too/ Kit User’s Guide and the CORE Graphics Library Manual. 
Facilities exist in the following areas: 


1. P/OS user interface support: the Tool Kit BASIC-PLUS-2 application 
has access to P/OS menu, help, message, and other system services. 
The ability to display error messages, status, on-line Help, and menus 
on the screen is provided through the P/OS Service Routines Library. 


2. Extended software functions: the Tool Kit BASIC-PLUS-2 application 
can invoke callable system services, such as PROSE (the P/OS text 
editor) and the PRO/Communications. 


P/OS facilities are accessed through the register 5 (R5) calling sequence with 
the BASIC-PLUS-2 CALL BY REF statement. 
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Tool Kit BASIC-PLUS-2 Development Cycle 
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Table 1 


Tool Kit BASIC-PLUS-2—ltems of Interest 


Feature 


Compiler Commands 
RUN 
LOAD 
BUILD 
BUILD/DUMP 
BUILD/NOSEQUENTIAL 
BUILD/CLUSTER 


SET DUMP — 

SET NOSEQUENTIAL 
Debugger Commands 

REDIRECT 


Error Messages 


Immediate Mode 
Magnetic Tape Operations 
RMS Support 
Statements 

CHAIN 


FSS$ Function 
EDIT$ 


Time Format 


CTRL/C Trapping 


DECnet file access (DAP) 


Please Note 


Not in the Tool Kit compiler. 

Not in the Tool Kit compiler. 

.CMD and .ODL files may need to be edited. 
Unsupported. 

Unsupported for programs that do not access RMS files. 


You can cluster one library in addition to POSRES, RMSRES, 
and BP2SML, which are added by default. 


Unsupported. 


Unsupported for programs that do not access RMS files. 


Allows debugging during application execution from a terminal 
attached to the Professional. Does not accept terminal device 
number. 


A subset of error messages for BASIC-PLUS-2 on RSX. You 
must press RESUME to continue after receiving error mes- 
sage. 


Not in Tool Kit compiler. 
Unsupported. 


Must not be removed from task image. 


Accepts installed task name, same as name in application 
installation file (not file specification). 


Unsupported for named directories. 


Do not use any odd integer as argument to EDIT$ if the string 
to be operated on is an 8-bit character: high-order bit will be 
cleared. 


Twelve-hour AM/PM format unsupported. 


Enabling CTRL/C trapping causes the terminal to be attached. 
Some of the callable P/OS routines can not be called if the ter- 
minal is attached (see the Too! Kit User’s Guide). 


Unsupported. 


3.1.1. Differences and Unsupported Features—Table 1 summarizes fea- 
tures that will influence your source code. Some operate differently than on 
RSX systems, others are unsupported. Do not use the unsupported features lis- 
ted here when you write an application using Tool Kit BASIC-PLUS-2. 


For more information on editing the command and overlay descriptor files, see 
Sections 3.5 and 3.6 of this supplement. For a complete list of Tool Kit BASIC- 
PLUS-2 error messages, see Section 4. 
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3.2 Character Sets 


Tool Kit BASIC-PLUS-2 supports the DEC Multinational Character Set in string 
literals, comments, and DATA statements when you compile the application, 
and as input or output when you run the application on the Professional. (See 
the Terminal Subsystem Manual for a description of the DEC Multinational 
Character Set.) 


The compiler does not allow European alphabetics in variable names. 


Do not use any odd integer as the argument to EDIT$ if the string to be operated 
on is an 8-bit character: the high-order bit will be cleared. 


3.3 Compiling the Source Program 


When you install Tool Kit BASIC-PLUS-2 on your host system, you select the 
Extended Instruction Set (EIS) compiler, the Floating Point. Unit (FPU) compiler, 
or both, as part of the installation process. Your choice should reflect the envi- 
ronment in which your applications will run. Floating Point hardware is optional 
on the Professional. Your host development system does not require an FPU to 
run the Tool Kit FPU compiler. Build your programs with the FPU compiler only if 
your applications will run on Professionals which have the Floating Point option. 


To invoke the EIS compiler on RSX-11M/11M-PLUS, type: 

>RUN $PBE 
To invoke the FPU compiler, type: 

>RUN $PBF 
To invoke the EIS compiler on VAX/VMS, use the command: 

$ RUN SYS$SYSTEM:PBE 
To invoke the FPU compiler, use the command: 

$ RUN SYS$SYSTEM:PBF 
Compile your source program using the BASIC-PLUS-2 COMPILE command. 
The compiler will check each line of the source program for errors, returning an 
appropriate message if an error is found. You can then correct the program as 
necessary and recompile it. Program compilation produces an object module 
file (file. OBJ) that can be task built on the host system. 
BASIC-PLUS-2 has its own debugger. To use the debugger with your applica- 
tion, compile your source program using the /DEBUG qualifier. When you 


execute the application on the Professional, you can issue commands to the 
debugger to control and monitor application execution. 
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3.4 Generating the Command and Descriptor Files 


After compiling the program, use the BASIC-PLUS-2 BUILD command to gener- 
ate a command file (file-CMD) and overlay descriptor file (file; ODL) for your 
application. The Professional Application Builder (PAB) uses these files to 
define how libraries are referenced, and to specify special-purpose buffers, logi- 
cal unit numbers (LUNs), and event flags (EFNs). 


You may need to edit the command file and/or the overlay descriptor file before 
you task build. The following sections describe the conditions under which you 
might want to edit these files. 


3.4.1 Rebuilding an Application—lf you are rebuilding an application to use 
the FPU OTS, having first built it for the EIS OTS, you must change all occur- 
rences of PBE to PBF in the command and overlay descriptor files generated by 
the EIS compiler. You must also add the /FP switch to the task image output file 
specification in the command file. 


3.5 Editing the Command File 


A command file generated by the Tool Kit BASIC-PLUS-2 EIS compiler for an 
application named ''TEST1" would look like this (comments have been added 
to describe the entries). 


STETESTIZCPHSiY Ss TESTAMNP 
TASK=task-name 

UNITS = 18 

ASG = Tisi3219 

ASG = - SYiores/7sStoe ys tt she 

BAd bon. = Vee 

CLSTR = PBESML+RMSRES 1 POSRES: RO 


, DEPINE BUrTER Sil2es 


EXTSCT = DM#$BUF: 4340 5 dynamic single choice menu 

EXTSCT = FL&aBUFT4a43ToO 5 file selection/sPecification 
1 for ODFIL and NEWFIL routine 

EATGSGT. = HLSBUresaio 5 help text/mennu 

EXTSCT = MM#$BUF:1000 yj multi-screen menu 

EXTSCT = MNSBUF: 4540 3 Static single choice menu 


5 DEFINE LUN ASSIGNMENTS 


GBLDEF = HL#$LUN:21 5 hele frame file 

GBLDEF = MNSLUN: 20 5 menu frame file 

GBLDEF = MS#LUN:16 5 message frame file 

GBLDEF = TT#EFN:1 s terminal I/O event flag 

GBLDEF = TT$LUN:15 $ terminal I/O 

GBLDEF = WC#éLUN:22 5 directory searches for OLDFIL and NEWFIL 


5 Follitine or callable Print services 
ep 
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The values shown for the extend section lines (EXTSCT) are default values. 
They are calculated for the largest possible frame of each type. That is, if every 
field on a menu, help, and message frame were filled in with the maximum 
amount of data, the respective buffers should be allocated the sizes shown. To 
optimize buffer allocation you may want to reduce these values based on your 
application’s needs. 


3.6 Editing the Overlay Descriptor File 


The Tool Kit BASIC-PLUS-2 EIS compiler would produce this overlay descriptor 
file for the Tool Kit application TEST1: 


»ROOT BASIC2Z-RMSROT-USER + RMSALL 
USER: ar Conk SYtTIESTI-LIGR 
LIBR: »FOCTR Loti les JPBEUTS/L6G 
@LB:Ci+sSJPBEIC1 
@LB:CisSIRMSRLA 

»END 


If you want to reference any Tool Kit object libraries facilities, such as FMS-11, 
you should edit the .ODL file. The PRO/EMS-11 Documentation Supplement 
provides an example of the editing required to include FMS-11. In the general 
case, see BASIC on RSX-11M/M-PLUS Systems for information on editing 
BASIC-PLUS-2 .ODL files. 


3.7 Building the P/OS Task Images 


Use the Professional Application Builder (PAB) to create an application task 
image (file. TSK). See the Too/ Kit User’s Guide for complete information on 
Professional Application Builder commands. 


3.8 Debugging During Execution 


Use the BASIC-PLUS-2 debugger to debug the program. (See your BASIC doc- 
umentation for more information on the BASIC-PLUS-2 debugger.) In addition, 
when you execute a task on the Professional, you can also connect a terminal to 
the printer port on the Professional for debugging. (See the Joo/ Kit User's 
Guide for details.) Use the Tool Kit BASIC-PLUS-2 REDIRECT command to 
display debugger I/O and issue debugger commands on that terminal. Input is 
accepted from and output goes to the printer port. Note that the REDIRECT 
command does not accept a terminal device number. All other I/O, including 
graphics or forms, will remain unaffected. 


4.0 TOOL KIT BASIC-PLUS-2 RUN-TIME ERROR MESSAGES 


Tool Kit BASIC-PLUS-2 run-time error messages are a subset of BASIC- 
PLUS-2 run-time error messages on RSX systems. The Tool Kit BASIC-PLUS-2 
run-time error messages are preceded by a number to help you report the error. 
lf you use ERT$ to reference an error not in the Tool Kit BASIC-PLUS-2 subset, 
ERT$ will return the following message: 


Can‘’t access LB: Ci;+7IBASIC2.ERR or can’t find frame “ids 
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Frame <id> will identify the error number of the ERT$ you tried to reference. 


lf the debugger is not present, the following notice will appear on the screen 
after the error message is displayed: 


Please Write down the above message -- Press RESUME to continue, 


You must press the RESUME key to clear the screen and continue. 


Note: Error 135 is issued if indexed I/O is attempted on a P/OS Diskette appli- 
cation (as opposed to P/OS Hard Disk) 


Table 2 
Tool Kit BASIC-PLUS-2 Error Messages 


Number Text 


meh 


?Bad directory for device 


2 ? Illegal file name 
3 ?Account or device in use 
4 ?No room for user on device 
5 ?Can't find file or account 
6 ?Not a valid device 
7 71/0 channel already open 
8 ?Device not available 
9 21/0 channel not open 
10 ?Protection violation 
11 ?End of file on device 
12 ?Fatal system I/O failure 
13 ?User data error on device 
14 ?Device hung or write locked 
15 ?Keyboard wait exhausted 
19 ?Disk block is interlocked 
28 ?Programmable 4C trap 
3 ?|llegal byte count for I/O 
34 ?Reserved instruction trap 
35 ?Memory management violation 
43 ?Virtual array not on disk 
44 ?Matrix or array too big 
45 ?Virtual array not yet open 
46 ? Illegal I/O Channel 
47 ?Line too long 
48 %Floating point error 
50 %Data format error 
51 %\|nteger error 
52 ? Illegal number 


53 %lllegal argument in LOG 


Table 2 Continued 
Tool Kit BASIC-PLUS-2 Error Messages 
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Number Text 
54 % imaginary square roots 
55 ?Subscript out of range 
56 ?Can't invert matrix 
oY ?Out of data 
58 ?0ON statement out of range 
59 ?Not enough data in record 
60 ?Integer overflow, FOR loop 
61 %Division by 0 
63 ?FIELD overflows buffer 
64 ?Not a random access device 
72 ?RETURN without GOSUB 
73 ?FNEND without function call 
88 ?Arguments don’t match 
89 ?Too many arguments 
97 ?Too few arguments 
104 ?RESUME and no error 
105 ?Redimensioned array 
116 ?PRINT-USING format error 
126 ?Maximum memory exceeded 
127 %SCALE factor interlock 
130 ?Key not changeable 
131 ?No current record 
132 ?Record has been deleted 
133 ?\llegal usage for device 
134 ?Duplicate key detected 
135 ?\llegal usage 
136 ?\llegal or illogical access 
137 ?\llegal key attributes 
138 ?File is locked 
139 ?Invalid file options 
140 ? Index not initialized 
141 ?\llegal operation 
142 ?\llegal record on file 
143 ?Bad record identifier 
144 ? Invalid key of reference 
145 ?Key size too large 
147 ?RECORD number exceeds maximum 


148 ?Bad RECORDSIZE value on OPEN 


epee Sa at a a eg tee ae ae 
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Table 2 Continued 
Tool Kit BASIC-PLUS-2 Error Messages 


Number Text 

149 ?Not at end of file 

150 ?2No primary key specified 

151 ?Key field beyond end of record 
152 ?\llogical record accessing 
153 ?Record already exists 

154 ?Record/bucket locked 

155 ?Record not found 

156 ?Size of record invalid 

157 ?Record on file too big 

158 ?Primary key out of sequence 
159 ?Key larger than record 

160 ?File attributes not matched 
161 ?Move overflows buffer 

162 ?Cannot open file 

164 ?Terminal format file required 
166 ?Negative fill or string length 
167 ? Illegal record format 

168 ? Illegal ALLOW clause 

170 ?Index not fully optimized 

171 ?RRV not fully updated 

173 ?Invalid RFA field 

180 ?No support for op in task 

183 ?REMAP overflows buffer 
184 %Unaligned REMAP variable 
185 ?RECORDSIZE overflows MAP buffer 
186 ?Improper error handling 

227 ?String too long 

246 ?Error trap needs RESUME 
247 ? Illegal RESUME to subroutine 
248 ? Illegal return from subroutine 
250 ?Not implemented 

251 ?Recursive subroutine call 
252 ?FILE ACP failure 


253 ?Directive error 
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